Getting Started¶

This notebook introduces the basics of using xarray_plotly for interactive visualization.

Installation¶

pip install xarray_plotly

Or with uv:

uv add xarray_plotly

Basic Usage¶

Import the xpx function for full IDE code completion:

In [1]:

import numpy as np
import pandas as pd
import xarray as xr

from xarray_plotly import config, xpx

config.notebook()  # Configure Plotly for notebook rendering

import numpy as np import pandas as pd import xarray as xr from xarray_plotly import config, xpx config.notebook() # Configure Plotly for notebook rendering

Create Sample Data¶

Let's create a DataArray with multiple dimensions:

In [2]:

# Create sample climate data
np.random.seed(42)

da = xr.DataArray(
    np.random.randn(50, 3, 2).cumsum(axis=0),  # Random walk
    dims=["time", "city", "scenario"],
    coords={
        "time": pd.date_range("2020-01-01", periods=50, freq="D"),
        "city": ["New York", "Los Angeles", "Chicago"],
        "scenario": ["baseline", "warming"],
    },
    name="temperature",
    attrs={"long_name": "Temperature Anomaly", "units": "°C"},
)

da.to_dataframe()

# Create sample climate data np.random.seed(42) da = xr.DataArray( np.random.randn(50, 3, 2).cumsum(axis=0), # Random walk dims=["time", "city", "scenario"], coords={ "time": pd.date_range("2020-01-01", periods=50, freq="D"), "city": ["New York", "Los Angeles", "Chicago"], "scenario": ["baseline", "warming"], }, name="temperature", attrs={"long_name": "Temperature Anomaly", "units": "°C"}, ) da.to_dataframe()

Out[2]:

			temperature
time	city	scenario
2020-01-01	New York	baseline	0.496714
		warming	-0.138264
	Los Angeles	baseline	0.647689
		warming	1.523030
	Chicago	baseline	-0.234153
...	...	...	...
2020-02-19	New York	warming	-13.111345
	Los Angeles	baseline	-10.375200
		warming	-1.301501
	Chicago	baseline	-5.211987
		warming	17.857366

300 rows × 1 columns

Your First Plot¶

Create an interactive line plot with a single method call:

In [3]:

# Dimensions auto-assign: time→x, city→color, scenario→facet_col
fig = xpx(da).line()
fig

# Dimensions auto-assign: time→x, city→color, scenario→facet_col fig = xpx(da).line() fig

The plot is fully interactive:

• Zoom: Click and drag to select a region
• Pan: Hold shift and drag
• Hover: See exact values at each point
• Toggle traces: Click legend items to show/hide

Dimension Assignment¶

Dimensions are assigned to plot "slots" based on their order:

Dimension	Slot
time (1st)	x-axis
city (2nd)	color
scenario (3rd)	facet_col

You can override this with explicit assignments:

In [4]:

# Put scenario on color, city on facets
fig = xpx(da).line(color="scenario", facet_col="city")
fig

# Put scenario on color, city on facets fig = xpx(da).line(color="scenario", facet_col="city") fig

Skipping Slots¶

Use None to skip a slot entirely:

In [5]:

# Skip color, so city goes to line_dash instead
fig = xpx(da.sel(scenario="baseline")).line(color=None)
fig

# Skip color, so city goes to line_dash instead fig = xpx(da.sel(scenario="baseline")).line(color=None) fig

Customization¶

All methods return a Plotly Figure that you can customize:

In [6]:

fig = xpx(da).line()

fig.update_layout(
    title="Temperature Anomaly Projections",
    template="plotly_white",
    legend_title_text="City",
)

fig

fig = xpx(da).line() fig.update_layout( title="Temperature Anomaly Projections", template="plotly_white", legend_title_text="City", ) fig

You can also pass Plotly Express arguments directly:

In [7]:

fig = xpx(da).line(
    title="Temperature Trends",
    color_discrete_sequence=["#E63946", "#457B9D", "#2A9D8F"],
    template="simple_white",
)
fig

fig = xpx(da).line( title="Temperature Trends", color_discrete_sequence=["#E63946", "#457B9D", "#2A9D8F"], template="simple_white", ) fig

Configuration¶

Customize label extraction and other behavior with the config module:

In [8]:

# View current options
config.get_options()

# View current options config.get_options()

Out[8]:

{'label_use_long_name': True,
 'label_use_standard_name': True,
 'label_include_units': True,
 'label_unit_format': '[{units}]',
 'slot_orders': {'line': ('x',
   'color',
   'line_dash',
   'symbol',
   'facet_col',
   'facet_row',
   'animation_frame'),
  'bar': ('x',
   'color',
   'pattern_shape',
   'facet_col',
   'facet_row',
   'animation_frame'),
  'area': ('x',
   'color',
   'pattern_shape',
   'facet_col',
   'facet_row',
   'animation_frame'),
  'scatter': ('x',
   'color',
   'symbol',
   'facet_col',
   'facet_row',
   'animation_frame'),
  'imshow': ('y', 'x', 'facet_col', 'animation_frame'),
  'box': ('x', 'color', 'facet_col', 'facet_row', 'animation_frame')}}

Next Steps¶

• Explore different Plot Types
• Learn Advanced Usage patterns
• Check the API Reference